home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / lang / Math.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  18.9 KB  |  527 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Math.java    1.34 98/07/23
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16. import java.util.Random;
  17.  
  18.  
  19. /**
  20.  * The class <code>Math</code> contains methods for performing basic 
  21.  * numeric operations such as the elementary exponential, logarithm, 
  22.  * square root, and trigonometric functions. 
  23.  * <p>
  24.  * To help ensure portability of Java programs, the definitions of 
  25.  * many of the numeric functions in this package require that they 
  26.  * produce the same results as certain published algorithms. These 
  27.  * algorithms are available from the well-known network library 
  28.  * <code>netlib</code> as the package "Freely Distributable 
  29.  * Math Library" (<code>fdlibm</code>). These algorithms, which 
  30.  * are written in the C programming language, are then to be 
  31.  * understood as executed with all floating-point operations 
  32.  * following the rules of Java floating-point arithmetic. 
  33.  * <p>
  34.  * The network library may be found on the World Wide Web at:
  35.  * <blockquote><pre>
  36.  *   http://sunsite.unc.edu/
  37.  * </pre></blockquote>
  38.  * <p>
  39.  * The Java math library is defined with respect to the version of 
  40.  * <code>fdlibm</code> dated January 4, 1995. Where 
  41.  * <code>fdlibm</code> provides more than one definition for a 
  42.  * function (such as <code>acos</code>), use the "IEEE 754 core 
  43.  * function" version (residing in a file whose name begins with 
  44.  * the letter <code>e</code>). 
  45.  *
  46.  * @author  unascribed
  47.  * @version 1.34, 07/23/98
  48.  * @since   JDK1.0
  49.  */
  50.  
  51. public final class Math {
  52.  
  53.     /**
  54.      * Don't let anyone instantiate this class.
  55.      */
  56.     private Math() {}
  57.  
  58.     /**
  59.      * The <code>double</code> value that is closer than any other to 
  60.      * <code>e</code>, the base of the natural logarithms. 
  61.      */
  62.     public static final double E = 2.7182818284590452354;
  63.  
  64.     /**
  65.      * The <code>double</code> value that is closer than any other to 
  66.      * <i>pi</i>, the ratio of the circumference of a circle to its diameter. 
  67.      */
  68.     public static final double PI = 3.14159265358979323846;
  69.  
  70.     /**
  71.      * Returns the trigonometric sine of an angle.
  72.      *
  73.      * @param   a   an angle, in radians.
  74.      * @return  the sine of the argument.
  75.      */
  76.     public static native double sin(double a);
  77.     
  78.     /**
  79.      * Returns the trigonometric cosine of an angle.
  80.      *
  81.      * @param   a   an angle, in radians.
  82.      * @return  the cosine of the argument.
  83.      */
  84.     public static native double cos(double a);
  85.    
  86.     /**
  87.      * Returns the trigonometric tangent of an angle.
  88.      *
  89.      * @param   a   an angle, in radians.
  90.      * @return  the tangent of the argument.
  91.      */
  92.     public static native double tan(double a);
  93.  
  94.     /**
  95.      * Returns the arc sine of an angle, in the range of -<i>pi</i>/2 through
  96.      * <i>pi</i>/2.
  97.      *
  98.      * @param   a   the <code>double</code> value whose arc sine is to 
  99.      *              be returned.
  100.      * @return  the arc sine of the argument.
  101.      */
  102.     public static native double asin(double a);
  103.  
  104.     /**
  105.      * Returns the arc cosine of an angle, in the range of 0.0 through
  106.      * <i>pi</i>.
  107.      *
  108.      * @param   a   the <code>double</code> value whose arc cosine is to 
  109.      *              be returned.
  110.      * @return  the arc cosine of the argument.
  111.      */
  112.     public static native double acos(double a); 
  113.  
  114.     /**
  115.      * Returns the arc tangent of an angle, in the range of -<i>pi</i>/2
  116.      * through <i>pi</i>/2.
  117.      *
  118.      * @param   a   the <code>double</code> value whose arc tangent is to 
  119.      *              be returned.
  120.      * @return  the arc tangent of the argument.
  121.      */
  122.     public static native double atan(double a);
  123.  
  124.     /**
  125.      * Converts an angle measured in degrees to the equivalent angle
  126.      * measured in radians.
  127.      *
  128.      * @param   angdeg   an angle, in degrees
  129.      * @return  the measurement of the angle <code>angdeg</code>
  130.      *          in radians.
  131.      * @since   JDK1.2
  132.      */
  133.     public static double toRadians(double angdeg) {
  134.     return angdeg / 180.0 * PI;
  135.     }
  136.  
  137.     /**
  138.      * Converts an angle measured in radians to the equivalent angle
  139.      * measured in degrees.
  140.      *
  141.      * @param   angrad   an angle, in radians
  142.      * @return  the measurement of the angle <code>angrad</code>
  143.      *          in degrees.
  144.      * @since   JDK1.2
  145.      */
  146.     public static double toDegrees(double angrad) {
  147.     return angrad * 180.0 / PI;
  148.     }
  149.  
  150.     /**
  151.      * Returns the exponential number <i>e</i> (i.e., 2.718...) raised to
  152.      * the power of a <code>double</code> value.
  153.      *
  154.      * @param   a   a <code>double</code> value.
  155.      * @return  the value <i>e</i><sup>a</sup>, where <i>e</i> is the base of
  156.      *          the natural logarithms.
  157.      */
  158.     public static native double exp(double a);
  159.  
  160.     /**
  161.      * Returns the natural logarithm (base <i>e</i>) of a <code>double</code>
  162.      * value.
  163.      *
  164.      * @param   a   a number greater than <code>0.0</code>.
  165.      * @return  the value ln <code>a</code>, the natural logarithm of
  166.      *          <code>a</code>.
  167.      */
  168.     public static native double log(double a);
  169.  
  170.     /**
  171.      * Returns the square root of a <code>double</code> value.
  172.      *
  173.      * @param   a   a <code>double</code> value.
  174.      * <!--@return  the value of √ <code>a</code>.-->
  175.      * @return  the square root of <code>a</code>.
  176.      *          If the argument is NaN or less than zero, the result is NaN.
  177.      */
  178.     public static native double sqrt(double a);
  179.  
  180.     /**
  181.      * Computes the remainder operation on two arguments as prescribed 
  182.      * by the IEEE 754 standard.
  183.      * The remainder value is mathematically equal to 
  184.      * <code>f1 - f2</code> × <i>n</i>,
  185.      * where <i>n</i> is the mathematical integer closest to the exact 
  186.      * mathematical value of the quotient <code>f1/f2</code>, and if two 
  187.      * mathematical integers are equally close to <code>f1/f2</code>, 
  188.      * then <i>n</i> is the integer that is even. If the remainder is 
  189.      * zero, its sign is the same as the sign of the first argument. 
  190.      *
  191.      * @param   f1   the dividend.
  192.      * @param   f2   the divisor.
  193.      * @return  the remainder when <code>f1</code> is divided by
  194.      *          <code>f2</code>.
  195.      */
  196.     public static native double IEEEremainder(double f1, double f2);
  197.  
  198.     /**
  199.      * Returns the smallest (closest to negative infinity) 
  200.      * <code>double</code> value that is not less than the argument and is 
  201.      * equal to a mathematical integer. 
  202.      *
  203.      * @param   a   a <code>double</code> value.
  204.      * <!--@return  the value ⌈ <code>a</code> ⌉.-->
  205.      * @return  the smallest (closest to negative infinity) 
  206.      *          <code>double</code> value that is not less than the argument
  207.      *          and is equal to a mathematical integer. 
  208.      */
  209.     public static native double ceil(double a);
  210.  
  211.     /**
  212.      * Returns the largest (closest to positive infinity) 
  213.      * <code>double</code> value that is not greater than the argument and 
  214.      * is equal to a mathematical integer. 
  215.      *
  216.      * @param   a   a <code>double</code> value.
  217.      * @param   a   an assigned value.
  218.      * <!--@return  the value ⌊ <code>a</code> ⌋.-->
  219.      * @return  the largest (closest to positive infinity) 
  220.      *          <code>double</code> value that is not greater than the argument
  221.      *          and is equal to a mathematical integer. 
  222.      */
  223.     public static native double floor(double a);
  224.  
  225.     /**
  226.      * returns the closest integer to the argument. 
  227.      *
  228.      * @param   a   a <code>double</code> value.
  229.      * @return  the closest <code>double</code> value to <code>a</code> that is
  230.      *          equal to a mathematical integer. If two <code>double</code>
  231.      *          values that are mathematical integers are equally close to the
  232.      *          value of the argument, the result is the integer value that
  233.      *          is even.
  234.      */
  235.     public static native double rint(double a);
  236.  
  237.     /**
  238.      * Converts rectangular coordinates (<code>b</code>, <code>a</code>)
  239.      * to polar (r, <i>theta</i>).
  240.      * This method computes the phase <i>theta</i> by computing an arc tangent
  241.      * of <code>a/b</code> in the range of -<i>pi</i> to <i>pi</i>.
  242.      *
  243.      * @param   a   a <code>double</code> value.
  244.      * @param   b   a <code>double</code> value.
  245.      * @return  the <i>theta</i> component of the point
  246.      *          (<i>r</i>, <i>theta</i>)
  247.      *          in polar coordinates that corresponds to the point
  248.      *          (<i>b</i>, <i>a</i>) in Cartesian coordinates.
  249.      */
  250.     public static native double atan2(double a, double b);
  251.  
  252.  
  253.     /**
  254.      * Returns of value of the first argument raised to the power of the
  255.      * second argument.
  256.      * <p>
  257.      * If (<code>a == 0.0</code>), then <code>b</code> must be
  258.      * greater than <code>0.0</code>; otherwise an exception is thrown. 
  259.      * An exception also will occur if (<code>a <= 0.0</code>)
  260.      * and <code>b</code> is not equal to a whole number.
  261.      *
  262.      * @param   a   a <code>double</code> value.
  263.      * @param   b   a <code>double</code> value.
  264.      * @return  the value <code>a<sup>b</sup></code>.
  265.      * @exception ArithmeticException  if (<code>a == 0.0</code>) and
  266.      *              (<code>b <= 0.0</code>), or
  267.      *              if (<code>a <= 0.0</code>) and <code>b</code>
  268.      *              is not equal to a whole number.
  269.      */
  270.     public static native double pow(double a, double b);
  271.  
  272.     /**
  273.      * Returns the closest <code>int</code> to the argument. 
  274.      * <p>
  275.      * If the argument is negative infinity or any value less than or 
  276.      * equal to the value of <code>Integer.MIN_VALUE</code>, the result is 
  277.      * equal to the value of <code>Integer.MIN_VALUE</code>. 
  278.      * <p>
  279.      * If the argument is positive infinity or any value greater than or 
  280.      * equal to the value of <code>Integer.MAX_VALUE</code>, the result is 
  281.      * equal to the value of <code>Integer.MAX_VALUE</code>. 
  282.      *
  283.      * @param   a   a <code>float</code> value.
  284.      * @return  the value of the argument rounded to the nearest
  285.      *          <code>int</code> value.
  286.      * @see     java.lang.Integer#MAX_VALUE
  287.      * @see     java.lang.Integer#MIN_VALUE
  288.      */
  289.     public static int round(float a) {
  290.     return (int)floor(a + 0.5f);
  291.     }
  292.  
  293.     /**
  294.      * Returns the closest <code>long</code> to the argument. 
  295.      * <p>
  296.      * If the argument is negative infinity or any value less than or 
  297.      * equal to the value of <code>Long.MIN_VALUE</code>, the result is 
  298.      * equal to the value of <code>Long.MIN_VALUE</code>. 
  299.      * <p>
  300.      * If the argument is positive infinity or any value greater than or 
  301.      * equal to the value of <code>Long.MAX_VALUE</code>, the result is 
  302.      * equal to the value of <code>Long.MAX_VALUE</code>. 
  303.      *
  304.      * @param   a   a <code>double</code> value.
  305.      * @return  the value of the argument rounded to the nearest
  306.      *          <code>long</code> value.
  307.      * @see     java.lang.Long#MAX_VALUE
  308.      * @see     java.lang.Long#MIN_VALUE
  309.      */
  310.     public static long round(double a) {
  311.     return (long)floor(a + 0.5d);
  312.     }
  313.  
  314.     private static Random randomNumberGenerator;
  315.  
  316.     /**
  317.      * Returns a random number greater than or equal to <code>0.0</code> 
  318.      * and less than <code>1.0</code>. Returned values are chosen 
  319.      * pseudorandomly with (approximately) uniform distribution from that 
  320.      * range. 
  321.      * <p>
  322.      * When this method is first called, it creates a single new 
  323.      * pseudorandom-number generator, exactly as if by the expression 
  324.      * <blockquote><pre>new java.util.Random</pre></blockquote>
  325.      * This new pseudorandom-number generator is used thereafter for all 
  326.      * calls to this method and is used nowhere else. 
  327.      * <p>
  328.      * This method is properly synchronized to allow correct use by more 
  329.      * than one thread. However, if many threads need to generate 
  330.      * pseudorandom numbers at a great rate, it may reduce contention for 
  331.      * each thread to have its own pseudorandom-number generator.
  332.      *  
  333.      * @return  a pseudorandom <code>double</code> greater than or equal 
  334.      * to <code>0.0</code> and less than <code>1.0</code>.
  335.      * @see     java.util.Random#nextDouble()
  336.      */
  337.     public static synchronized double random() {
  338.         if (randomNumberGenerator == null)
  339.             randomNumberGenerator = new Random();
  340.         return randomNumberGenerator.nextDouble();
  341.     }
  342.  
  343.     /**
  344.      * Returns the absolute value of an <code>int</code> value.
  345.      * If the argument is not negative, the argument is returned.
  346.      * If the argument is negative, the negation of the argument is returned. 
  347.      * <p>
  348.      * Note that if the argument is equal to the value of 
  349.      * <code>Integer.MIN_VALUE</code>, the most negative representable 
  350.      * <code>int</code> value, the result is that same value, which is 
  351.      * negative. 
  352.      *
  353.      * @param   a   an <code>int</code> value.
  354.      * @return  the absolute value of the argument.
  355.      * @see     java.lang.Integer#MIN_VALUE
  356.      */
  357.     public static int abs(int a) {
  358.     return (a < 0) ? -a : a;
  359.     }
  360.  
  361.     /**
  362.      * Returns the absolute value of a <code>long</code> value.
  363.      * If the argument is not negative, the argument is returned.
  364.      * If the argument is negative, the negation of the argument is returned. 
  365.      * <p>
  366.      * Note that if the argument is equal to the value of 
  367.      * <code>Long.MIN_VALUE</code>, the most negative representable 
  368.      * <code>long</code> value, the result is that same value, which is 
  369.      * negative. 
  370.      *
  371.      * @param   a   a <code>long</code> value.
  372.      * @return  the absolute value of the argument.
  373.      * @see     java.lang.Long#MIN_VALUE
  374.      */
  375.     public static long abs(long a) {
  376.     return (a < 0) ? -a : a;
  377.     }
  378.  
  379.     /**
  380.      * Returns the absolute value of a <code>float</code> value.
  381.      * If the argument is not negative, the argument is returned.
  382.      * If the argument is negative, the negation of the argument is returned. 
  383.      *
  384.      * @param   a   a <code>float</code> value.
  385.      * @return  the absolute value of the argument.
  386.      */
  387.     public static float abs(float a) {
  388.         return (a <= 0.0F) ? 0.0F - a : a;
  389.     }
  390.   
  391.     /**
  392.      * Returns the absolute value of a <code>double</code> value.
  393.      * If the argument is not negative, the argument is returned.
  394.      * If the argument is negative, the negation of the argument is returned. 
  395.      *
  396.      * @param   a   a <code>double</code> value.
  397.      * @return  the absolute value of the argument.
  398.      */
  399.     public static double abs(double a) {
  400.         return (a <= 0.0D) ? 0.0D - a : a;
  401.     }
  402.  
  403.     /**
  404.      * Returns the greater of two <code>int</code> values.
  405.      *
  406.      * @param   a   an <code>int</code> value.
  407.      * @param   b   an <code>int</code> value.
  408.      * @return  the larger of <code>a</code> and <code>b</code>.
  409.      */
  410.     public static int max(int a, int b) {
  411.     return (a >= b) ? a : b;
  412.     }
  413.  
  414.     /**
  415.      * Returns the greater of two <code>long</code> values.
  416.      *
  417.      * @param   a   a <code>long</code> value.
  418.      * @param   b   a <code>long</code> value.
  419.      * @return  the larger of <code>a</code> and <code>b</code>.
  420.      */
  421.     public static long max(long a, long b) {
  422.     return (a >= b) ? a : b;
  423.     }
  424.  
  425.     private static long negativeZeroFloatBits = Float.floatToIntBits(-0.0f);
  426.     private static long negativeZeroDoubleBits = Double.doubleToLongBits(-0.0d);
  427.  
  428.     /**
  429.      * Returns the greater of two <code>float</code> values.  If either value
  430.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  431.      * the numerical comparison operators, this method considers negative zero
  432.      * to be strictly smaller than positive zero.
  433.      *
  434.      * @param   a   a <code>float</code> value.
  435.      * @param   b   a <code>float</code> value.
  436.      * @return  the larger of <code>a</code> and <code>b</code>.
  437.      */
  438.     public static float max(float a, float b) {
  439.         if (a != a) return a;    // a is NaN
  440.     if ((a == 0.0f) && (b == 0.0f)
  441.         && (Float.floatToIntBits(a) == negativeZeroFloatBits)) {
  442.         return b;
  443.     }
  444.     return (a >= b) ? a : b;
  445.     }
  446.  
  447.     /**
  448.      * Returns the greater of two <code>double</code> values.  If either value
  449.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  450.      * the numerical comparison operators, this method considers negative zero
  451.      * to be strictly smaller than positive zero.
  452.      *
  453.      * @param   a   a <code>double</code> value.
  454.      * @param   b   a <code>double</code> value.
  455.      * @return  the larger of <code>a</code> and <code>b</code>.
  456.      */
  457.     public static double max(double a, double b) {
  458.         if (a != a) return a;    // a is NaN
  459.     if ((a == 0.0d) && (b == 0.0d)
  460.         && (Double.doubleToLongBits(a) == negativeZeroDoubleBits)) {
  461.         return b;
  462.     }
  463.     return (a >= b) ? a : b;
  464.     }
  465.  
  466.     /**
  467.      * Returns the smaller of two <code>int</code> values.
  468.      *
  469.      * @param   a   an <code>int</code> value.
  470.      * @param   b   an <code>int</code> value.
  471.      * @return  the smaller of <code>a</code> and <code>b</code>.
  472.      */
  473.     public static int min(int a, int b) {
  474.     return (a <= b) ? a : b;
  475.     }
  476.  
  477.     /**
  478.      * Returns the smaller of two <code>long</code> values.
  479.      *
  480.      * @param   a   a <code>long</code> value.
  481.      * @param   b   a <code>long</code> value.
  482.      * @return  the smaller of <code>a</code> and <code>b</code>.
  483.      */
  484.     public static long min(long a, long b) {
  485.     return (a <= b) ? a : b;
  486.     }
  487.  
  488.     /**
  489.      * Returns the smaller of two <code>float</code> values.  If either value
  490.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  491.      * the numerical comparison operators, this method considers negative zero
  492.      * to be strictly smaller than positive zero.
  493.      *
  494.      * @param   a   a <code>float</code> value.
  495.      * @param   b   a <code>float</code> value.
  496.      * @return  the smaller of <code>a</code> and <code>b.</code>
  497.      */
  498.     public static float min(float a, float b) {
  499.         if (a != a) return a;    // a is NaN
  500.     if ((a == 0.0f) && (b == 0.0f)
  501.         && (Float.floatToIntBits(b) == negativeZeroFloatBits)) {
  502.         return b;
  503.     }
  504.     return (a <= b) ? a : b;
  505.     }
  506.  
  507.     /**
  508.      * Returns the smaller of two <code>double</code> values.  If either value
  509.      * is <code>NaN</code>, then the result is <code>NaN</code>.  Unlike the
  510.      * the numerical comparison operators, this method considers negative zero
  511.      * to be strictly smaller than positive zero.
  512.      *
  513.      * @param   a   a <code>double</code> value.
  514.      * @param   b   a <code>double</code> value.
  515.      * @return  the smaller of <code>a</code> and <code>b</code>.
  516.      */
  517.     public static double min(double a, double b) {
  518.         if (a != a) return a;    // a is NaN
  519.     if ((a == 0.0d) && (b == 0.0d)
  520.         && (Double.doubleToLongBits(b) == negativeZeroDoubleBits)) {
  521.         return b;
  522.     }
  523.     return (a <= b) ? a : b;
  524.     }
  525.  
  526. }
  527.